feat(enterprise-import): reconcile de emails em sessão persistida - #19

Summary

Reescreve o fluxo super-admin de conciliação de emails mascarados (import Enterprise) para operar em lotes sobre uma sessão server-side, viável para exports grandes (centenas de milhares de contatos, com milhares de colisões de máscara):

• Sessão persistida (email_reconcile_sessions/_items, migration 1783000000000): CSV parseado e matched uma vez; depois tudo é incremental — apply-auto em chunks, fila de ambíguos paginada, resolve em lote (best-name / skip-remaining), progresso derivado dos status. A substituição da sessão é transacional: rewrite interrompida não deixa cabeçalho com itens parciais.
• Match em camadas por created_at: o import preserva o timestamp da origem e o export CSV carrega o mesmo campo, então (máscara, created_at) age como chave natural. Tier de minuto exato > mesma data > desempate por similaridade de nome (Jaccard, insensível a pontuação/ordem).
• Um único offset de timezone por CSV: quando os timestamps não trazem offset, ele é inferido uma vez — pela moda dos deltas dos pares em que a máscara colide 1:1 dos dois lados, onde o pareamento é certo — e o tier exato exige esse valor. Amostra pequena ou sem dominância não vira palpite: o match para no nível de data e a decisão fica com o operador.
• Formatos de created_at aceitos: ISO/SQL, DD/MM/YYYY e o Date.prototype.toString() que o export em stream emitia (Thu Jul 09 2026 03:48:16 GMT-0300 (...)). O exportador passou a escrever ISO-8601 UTC, mas CSVs baixados antes disso continuam funcionando em vez de virarem created_at nulo — que degradava o match para nome, silenciosamente.
• Colunas obrigatórias validadas nos headers antes de processar (email, created_at e sinal de nome — coluna name ou par first_name/last_name); formulário de upload trava as obrigatórias e permite ignorar opcionais.
• Email como chave única por conta em todo o fluxo: arbitragem de auto-picks por email normalizado (exports repetem o mesmo endereço em várias linhas; chavear por linha deixava cada duplicata gerar seu próprio vencedor), pré-checagem no apply em vez do erro cru do índice único, candidatos já usados desabilitados na UI e estratégias automáticas nunca consomem email já aplicado.
• Endereço em uso vira conflito revisável, não falha: status conflict — terminal para as passadas automáticas (repetir daria o mesmo resultado, e deixar pendente faria o cliente rodar em loop), mas resolvível: o item aparece na fila de revisão, entra no resolve, é varrido pelo skip-remaining e pode ser reaberto em lote (POST session/reopen-conflicts) depois que o operador libera os endereços. Picks automáticos com endereço ocupado já nascem em conflito, sem gastar uma tentativa de apply para descobrir.
• Visibilidade: tabela "itens da sessão" (quem casou com o quê) com busca por nome/email e filtros de tipo/status (inclusive conflict); busca também na fila de ambíguos; badges de concordância de data; painel de conflitos com ação de reabertura.
• Cadeia de limites de upload alinhada: nginx client_max_body_size 64m + proxy_read_timeout 300s no /api, body-parser 64mb escopado em /imports, Joi 50MB.
• Leitura de email cru sob a permissão de export: a máscara do email real é idêntica ao placeholder importado, então contatos reconciliados pareciam continuar mascarados e o endereço utilizável não chegava a quem consome a API. As rotas de leitura passam a devolver o valor armazenado, mas só para quem tem audience:contacts_export (ou super admin) — a mesma fronteira que já protege o export do mesmo dado. Só contacts_view continua vendo a máscara, assim como chamadas sem contexto de principal. Supressões seguem mascaradas.

Test plan

• reconcile-timestamp.util.spec.ts (13): formatos aceitos/rejeitados, inferência do offset (moda, amostra insuficiente, sem dominância, timestamps que já trazem offset) e os níveis de concordância sob cada caso.
• email-reconcile.service.spec.ts (31): colunas obrigatórias (ambas as formas de nome), desambiguação por created_at, offset inferido vs ausente, CSV parcial vs colisões de máscara, arbitragem de endereço duplicado e o apply legado.
• email-reconcile-session.service.spec.ts (18): criação transacional da sessão, conflito pré-marcado, apply-auto (aplicado/conflito/falha e término do loop), resolve alcançando itens em conflito, bulk best-name não consumindo endereço ocupado, reabertura e contadores.
• enterprise-import.controller.spec.ts (9): contrato dos endpoints da sessão, clamps de paginação e filtros ignorados quando desconhecidos.
• export-timestamp.util.spec.ts (4) e email-visibility.util.spec.ts (8): regressão do contrato ISO do export e da fronteira de permissão do email cru.
• reconcile-gateway.test.ts (8, frontend): rotas, ausência de timeout no upload, filtro de conflito e reabertura.
• Suíte de backend completa verde (64 suítes / 850 testes); tsc --noEmit limpo em backend e frontend; locales pt-BR/en-US/es-ES válidos.
• Validado e2e no stack docker vivo com um export real: sessão criada, match automático por minuto, apply com re-derivação de hashed_email (listener @BeforeUpdate), auditoria registrada, busca e tabela de itens exercitadas contra a sessão viva.

Notas

• Swagger nos endpoints da sessão (@ApiOperation/@ApiQuery).
• O repositório só tem docker-build.yml; não há workflow de teste para rodar as suítes acima no CI. Fica como item de infra em PR próprio.